Skip to content

ci: Lab swizzle samples live with Lab, and pnpm lab:sync writes a new Lab component's route-lock entries and sample stub - #13019

Draft
cixzhang wants to merge 3 commits into
mainfrom
ci/lab-sync
Draft

cixzhang wants to merge 3 commits into
mainfrom
ci/lab-sync

Conversation

@cixzhang

Copy link
Copy Markdown
Contributor

Who this helps

Authors of Lab components. A new Lab component used to need hand edits to two shared files before its pull request could merge: the shadcn route lock (internal/shadcn-registry/routes.lock.json) and the swizzle proof's samples (packages/cli/test/swizzle-proof/samples.mjs). #9832 merged without its MediaPlayer sample and turned main's unit run red. With this change, a Lab-only pull request keeps everything Lab-local, and one command writes the rest.

Record: AST-030 FR26 at #12985 12f9b7a (the Lab lane, pnpm lab:sync, and packages/lab/swizzle-samples.mjs).

What changes

  • packages/lab/swizzle-samples.mjs (new): every lab__* swizzle sample and the Lab needsNoSample mark, moved from samples.mjs with the helpers only Lab samples use (noop and dotIcon are copied, since Core samples use them too). samples.mjs imports and spreads them. The behavior is identical: the same 102 sample keys, every sample function's source text equal, and needsNoSample and notRendered equal (checked by importing both versions). The file isn't published (not in the Lab package's files).
  • scripts/lab-sync.mjs (pnpm lab:sync [--check]):
    • Route lock: each Lab component, hook, example and showcase entry is derived from the Lab docs by the docsite generator's own rules: sub-component docs, family docs with or without top-level props, name-only references skipped, use… or params as hooks, Lab blocks as examples or showcases. Names and paths come from the docsite's identity helpers (componentRegistryIdentity, blockRegistryIdentity in apps/docsite/src/lib/shadcnRegistry.mjs), the ones checkShadcnRouteLock checks against. Missing or changed entries are written in the generator's order (by path) and format; other entries are untouched.
    • Samples: for each Lab target (lab__<doc file>) whose doc names a required prop that its defaults leave out, and that has no sample and no mark, it adds a stub above a marker line. Prop values come from the doc type: string → the prop name, number → 0, boolean → false, node → 'Sample', function → noop, a string-literal union → its first literal, an array → []. Each stub is marked // generated by lab:sync; edit freely, and an existing sample is never changed.
    • --check writes nothing. It names each missing entry with its file, prints "Run pnpm lab:sync and commit the result.", and exits 1.
  • scripts/preflight.mjs: both modes run pnpm lab:sync --check as a light check.
  • package.json adds the script, and docs/contributing/pull-requests.md gets a short paragraph plus the check in the preflight lists.

The Lab lane (CI) running lab:sync --check comes in the follow-up pull request that updates change-scope.

Tests

  • scripts/lab-sync.test.mjs:
    • On this repository: nothing is missing, so --check passes on main and feat(lab): add VideoPlayer and AudioPlayer media players #9832's routes and MediaPlayer sample are all there.
    • Generator equivalence: a lock with every Lab entry removed is written back byte-identical to the committed lock, which is the generator's own output.
    • A fixture Lab component missing both gets its route entry and stub, and an existing sample stays byte-identical. --check (the CLI) exits 1 before the sync, naming both entries and the fix, and exits 0 after it.
    • Stub values for each type.
    • The tests were written before the script, so the first red was the missing module.
  • samples.test.mjs and scope.test.mjs pass with the samples split; preflight.test.mjs passes with the new check.
  • pnpm lab:sync --check on main: "every Lab route-lock entry and swizzle sample is present."
  • review:pre: 0 findings; check:changesets OK; Prettier clean.

CI impact

CI impact: none in this pull request (no workflow change). The test file adds about 3 s to a Node leg.

Overlap checked: #13005 (ours; it also edits scripts/preflight.mjs for --quick typecheck skips; separate solution, small textual overlap resolved by whichever merges second), #12891, #11082 (add their own components' samples to samples.mjs; a Lab sample there moves to the Lab file when they merge main)

Owning session: noopbot (a61f66c2), under CI & Release (ca77f950). Land path: the drain's serial merge loop, on green, CodeBunny approval and Specs' exact-head /approve-spec.

… Lab component's route-lock entries and sample stub
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 20, 2026 2:44pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026
@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟡 Reviewed (for maintainers only) Nov 20, 2026, 2:47 PM UTC

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: pnpm lab:sync still needs two fixes, and its direction also waits on an engineering owner.

  • scripts/lab-sync.mjs:66-148 re-implements the docsite generator's doc walk (generateComponentRegistry in apps/docsite/scripts/generate-data.mjs) and already differs from it on the docs export, skipped folders, hook detection and the XDS prefix, so move that derivation into one exported helper that both call, and call the swizzle proof's docOf and missingSample instead of copying them.
  • scripts/lab-sync.mjs:301 checks samples against the Lab file alone while samples.mjs spreads that file last, so a Lab sample kept in samples.mjs (as #11082 adds lab__Rating) is reported missing and pnpm lab:sync overrides it with a placeholder stub; count keys in samples.mjs as present and fail with a named error on a key defined in both files.

Approval also needs an engineering owner to accept the spec:AST-030 FR26 amendment in #12985 (Lab samples in packages/lab/swizzle-samples.mjs, and pnpm lab:sync), because FR26 on main names neither. An engineering owner records that decision by approving #12985 or by commenting /approve-spec <full head SHA> here, and the author may do so as an engineering owner. Both findings are unchanged at this head, and the sample split itself checks out.

Claims and files checked

Review mode: incremental; reason: none

  • Changed rules (0): none.
  • Claim: the Lab samples moved with the same keys, identical sources and equal marks: verified (102 keys, no source differs, both marks equal).
  • Claim: the Lab samples file is not published: verified (it is not in the Lab package's files).
  • Claim: noop and dotIcon are copied because Core samples still use them: verified (samples.mjs:14, :18, :267).
  • Claim: route entries follow the docsite generator's own rules: false, four divergences (first finding).
  • Claim: names and paths come from the docsite's identity helpers: verified (componentRegistryIdentity and blockRegistryIdentity).
  • Claim: missing or changed entries are written in the generator's order and format, and other entries are untouched: verified (the byte-identical lock test).
  • Claim: a stub is added for a Lab target with a required prop, no default, no sample and no mark, with values from the doc type: verified for the Lab file (stub tests); false for a sample kept in samples.mjs (second finding).
  • Claim: an existing sample is never changed: false (second finding).
  • Claim: --check writes nothing, names each missing entry and the fix, and exits 1: verified (CLI test and a reproduction).
  • Claim: preflight runs lab:sync --check in both modes: verified (preflight.mjs, preflight.test.mjs).
  • Claim: the tests pass and --check passes on the repository: verified (42 of 42 tests; --check exits 0).
  • Claim: no workflow changes: verified.
  • docs/contributing/pull-requests.md: its "never changes an existing sample" sentence is false (second finding).
  • package.json: clear.
  • packages/cli/test/swizzle-proof/samples.mjs: clear on its own; its spread order is part of the second finding.
  • packages/lab/swizzle-samples.mjs: clear.
  • scripts/lab-sync.mjs: both findings; its header also says CI's Lab lane runs it, which no workflow does yet.
  • scripts/lab-sync.test.mjs: clear; its fixture docs use export default, which the generator never reads (first finding).
  • scripts/preflight.mjs: clear.
  • scripts/preflight.test.mjs: clear.

Automated review (maintainer link)

Comment thread scripts/lab-sync.mjs
* @param {{componentRegistryIdentity: Function, blockRegistryIdentity: Function}} identity
* @returns {Promise<{name: string, path: string, aliases: string[]}[]>}
*/
export async function labRouteEntries(root, identity) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This walk re-implements generateComponentRegistry in apps/docsite/scripts/generate-data.mjs and already differs from it: the generator reads only the docs export, skips utils/__tests__/node_modules, treats any truthy doc.params as a hook, and keeps XDS in a standalone doc's name. Move the entry derivation into one exported helper (for example in apps/docsite/src/lib/) that both call.

Comment thread scripts/lab-sync.mjs
const targets = await unsampledTargets(
root,
{
samples: {...lab.labSamples},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only the Lab file's samples count here, but samples.mjs spreads them last, so a lab__* sample kept in samples.mjs (as #11082 adds lab__Rating) is reported missing, and pnpm lab:sync then adds a stub that overrides it in the proof. Count samples.mjs's own keys as present and fail with a named error on a key defined in both files.

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: pnpm lab:sync still needs two fixes, and its direction also waits on an engineering owner.

  • scripts/lab-sync.mjs:66-148 re-implements the docsite generator's doc walk (generateComponentRegistry in apps/docsite/scripts/generate-data.mjs) and already differs from it on the docs export, skipped folders, hook detection and the XDS prefix, so move that derivation into one exported helper that both call, and call the swizzle proof's docOf and missingSample instead of copying them.
  • scripts/lab-sync.mjs:301 checks samples against the Lab file alone while samples.mjs spreads that file last, so a Lab sample kept in samples.mjs (as #11082 adds lab__Rating) is reported missing and pnpm lab:sync overrides it with a placeholder stub; count keys in samples.mjs as present and fail with a named error on a key defined in both files.

Approval also needs an engineering owner to accept the spec:AST-030 FR26 amendment in #12985 (Lab samples in packages/lab/swizzle-samples.mjs, and pnpm lab:sync), because FR26 on main names neither. An engineering owner records that decision by approving #12985 or by commenting /approve-spec <full head SHA> here, and the author may do so as an engineering owner. Both findings are unchanged at this head, which only merges main, and the sample split itself checks out.

Claims and files checked

Review mode: incremental; reason: none

  • Changed rules (0): none.
  • Claim: the Lab samples moved with the same keys, identical sources and equal marks: verified (102 keys, no source differs, both marks equal).
  • Claim: noop and dotIcon are copied because Core samples still use them: verified (samples.mjs:14, :18, :267).
  • Claim: the Lab samples file is not published: verified (it is not in the Lab package's files).
  • Claim: route entries follow the docsite generator's own rules: false, four divergences (first finding).
  • Claim: names and paths come from the docsite's identity helpers: verified (componentRegistryIdentity and blockRegistryIdentity).
  • Claim: missing or changed entries are written in the generator's order and format, and other entries are untouched: verified (the byte-identical lock test).
  • Claim: a marked stub is added for a Lab target with a required prop, no default, no sample and no mark, with values from the doc type: verified for the Lab file (stub tests); false for a sample kept in samples.mjs (second finding).
  • Claim: an existing sample is never changed: false (second finding).
  • Claim: --check writes nothing, names each missing entry and the fix, and exits 1: verified (CLI test and a reproduction).
  • Claim: preflight runs lab:sync --check as a light check in both modes: verified (preflight.mjs, preflight.test.mjs).
  • Claim: the root script and the contributing guide's paragraph and preflight lists are added: verified.
  • Claim: the tests pass and --check passes on the repository: verified (44 of 44 tests; --check exits 0).
  • Claim: changesets and formatting checks pass: verified (check:changesets and Prettier on the changed files); the pre-review script was not rerun.
  • Claim: the new test file adds about 3 s to a Node leg: consistent (its 6 tests run in under 1 s).
  • Claim: no workflow changes, and the Lab lane runs the check in a follow-up: verified (no workflow in the diff).
  • Claim: the overlap with the preflight --quick change resolves cleanly: verified (the merge of main is clean).
  • Claim: an earlier Lab pull request merged without its sample and broke main: background, not rechecked.
  • docs/contributing/pull-requests.md: its "never changes an existing sample" sentence is false (second finding).
  • package.json: clear.
  • packages/cli/test/swizzle-proof/samples.mjs: clear on its own; its spread order is part of the second finding.
  • packages/lab/swizzle-samples.mjs: clear.
  • scripts/lab-sync.mjs: both findings; its header also says CI's Lab lane runs it, which no workflow does yet.
  • scripts/lab-sync.test.mjs: clear; its fixture docs use export default, which the generator never reads (first finding).
  • scripts/preflight.mjs: clear.
  • scripts/preflight.test.mjs: clear.

Automated review (maintainer link)

This branch was successfully deployed

1 active deployment
Preview — b434cc09 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant